<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">

<HTML>
  <HEAD>
    <META name="generator" content=
    "HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">

    <TITLE>Debugger: Emulation Service</TITLE>
    <META http-equiv="Content-Type" content="text/html; charset=windows-1252">
    <LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
  </HEAD>

  <BODY lang="EN-US">
    <H1><A name="plugin"></A>Debugger: Emulation Service</H1>

    <P>This service plugin provides emulation to the <A href=
    "help/topics/DebuggerTraceManagerServicePlugin/DebuggerTraceManagerServicePlugin.html">Trace
    Manager</A> and provides actions for launching emulated traces from programs, i.e., without
    requiring a connected debugger. Please note that "pure emulation" of a target program, while it
    doesn't require a platform to execute the target natively, it typically does require
    significant state initialization and dependency stubbing, except in limited circumstances.</P>

    <H2>Actions</H2>

    <H3><A name="emulate_program"></A> Emulate Program</H3>

    <P>This action is available whenever a program is active. It will create a new trace suitable
    for "pure emulation" of the current program starting at the current address. More precisely, it
    will open a new blank trace, initialize it with the current program's memory map, allocate a
    stack, and create a thread whose program counter is initialized to the current address and
    whose registers are initialized to the register context at that address. Optionally, any other
    initialization can be done by manually modifying the trace in the UI, or using a script. The <A
    href="help/topics/DebuggerControlPlugin/DebuggerControlPlugin.html#emu_actions">emulator
    controls</A> can then be used.</P>

    <P>To control the initial stack allocation, create a <CODE>STACK</CODE> block in the target
    program database before emulating. If the stack is already in the target image's memory map,
    create an overlay block named <CODE>STACK</CODE>. This will initialize the stack pointer
    without modifying the emulator's memory map. Note that customizing the stack initialization may
    prevent you from adding a second thread.</P>

    <H3><A name="add_emulated_thread"></A> Add Emulated Thread</H3>

    <P>This action is available whenever a "pure emulation" trace is active. It spawns a new thread
    in the current trace suitable for emulation starting at the current address. More precisely, it
    will allocate another stack and create a new thread whose program counter is initialized to the
    current address and whose registers are initialized to the register context at that address.
    Optionally, other registers can be initialized via the UI or a script. The new thread is
    activated so that control actions will affect it by default.</P>

    <H3><A name="configure_emulator"></A> Configure Emulator</H3>

    <P>This action is always available. It lists emulators available for configuration. Selecting
    one will set it as the current emulator. The next time emulation is activated, it will use the
    selected emulator.</P>

    <H3><A name="invalidate_cache"></A> Invalidate Emulator Cache</H3>

    <P>This action is available whenever a trace is active. It invalidates all the scratch
    snapshots in the current trace, which are used for caching emulated machine states. This is
    recommended when you change the emulator configuration, when you change the Sleigh code of an
    emulated breakpoint, or when you patch the trace database. If you do not invalidate the cache,
    the effects of your change may not appear, since the trace manager may recall a cached snapshot
    instead of actually emulating.</P>
  </BODY>
</HTML>
